%
% `SGIOChannel.tex' -- describes the SGIOChannel class
%
%  Written by Curtis Olson.  Started July, 2000.
%
% $Id: SGIOChannel.tex,v 1.1.1.1 2002/09/07 02:58:21 curt Exp $
%------------------------------------------------------------------------


\documentclass[12pt]{article}

\usepackage{anysize}
\papersize{11in}{8.5in}
\marginsize{1in}{1in}{1in}{1in}

\usepackage{amsmath}

\usepackage{epsfig}

\usepackage{setspace}
\onehalfspacing

\usepackage{url}


\begin{document}


\title{
    SimGear \texttt{SGIOChannel} classes.
}


\author{
    Curtis L. Olson (\texttt{curt@flightgear.org}) \\
}


\maketitle


\section{Introduction}

The \texttt{SGIOChannel} base class provides a consistent method for
applications to communication through various mediums.  By providing a
base class with multiple derived classes, and application such as
FlightGear can implement a way to speak any protocol via any kind of
I/O channel.


\section{Synopsis}

\begin{verbatim}
#include <simgear/io/sg_file.hxx>
#include <simgear/io/sg_serial.hxx>
#include <simgear/io/sg_socket.hxx>

SGFile   file  ( const string& file );
SGSerial serial( const string& device_name, const string& baud_rate );
SGSocket socket( const string& host, const string& port, const string& style );
\end{verbatim}


\section{Constructors}

All of the current three classes are derived from the
\texttt{SGIOChannel} class and provide a consistent API between them.
The only differences occur with the constructors and the accessor
methods.

\subsection{\texttt{SGFile} Constructor}

\begin{verbatim}
SGFile( const string& file );
\end{verbatim}

This creates an instance of the \texttt{SGFile} class.  When calling
the constructor you need to provide a file name.  This file is not
opened immediately, but instead will be opened when the
\texttt{open()} method is called.

\subsection{\texttt{SGSerial} Constructor}

\begin{verbatim}
SGSerial( const string& device_name, const string& baud_rate );
\end{verbatim}

This creates an instance of the \texttt{SGSerial} class.  You need to
provide the serial device name and desired baud rate.  For Unix style
systems, device names will be similar to ``\texttt{/dev/ttyS0}''.  For
DOS style systems you may want to use something similar to
``\texttt{COM1:}''.  As with the \texttt{SGFile} class, device is not
opened immediately, but instead will be opened when the
\texttt{open()} method is called.

\subsection{\texttt{SGSocket} Constructor}

\begin{verbatim}
SGSocket( const string& host, const string& port, const string& style );
\end{verbatim}

This creates an instance of the \texttt{SGSocket} class.  When calling
the constructor you need to provide a host name, a port number, and a
socket style.  The convention used by the \texttt{SGSocket} class is
that the server side listens and the client side sends.  For a server
socket, the host name should be empty.  For a server, the port number
is optional, if you do not specify a port, the system will assign one.
For a client socket, you need to specify both a destination host and
destination port.  For both client and server sockets you must specify
the socket type.  Type must be either \texttt{udp} or \texttt{tcp}.
Here's a quick breakdown of the major differences between UDP and TCP
type sockets.

TCP sockets are the type where you establish a connection and then can
read and write to the socket from both ends.  If one end of TCP socket
connect quits, the other end will likely segfault if it doesn't take
special precautions.  But, the nice thing about TCP connections is
that the underlying protocol guarantees that your message will get
through.  This imposes a certain performance overhead though on the
communication because the protocol must resend failed messages.  TCP
sockets are good for sending periodic command/response type messages
where performance isn't a big issues, but reliability is.

UDP sockets on the other hand are a lower level protocol and don't
have the same sort of connection as TCP sockets.  With UDP sockets,
the server end just sits and listens for incoming packets from
anywhere.  The client end sends it's message and forgets about it.  It
doesn't care if there isn't even a server out there listening and all
the packets are getting lost.  Although systems/networks usually do a
pretty good job (statistically) of getting your UDP packets to their
destination, there is no guarantee that any particular packet will
make it.  But, because of this low level implementation and lack of
error checking, UDP packets are much faster and efficient.  UDP
packets are good for sending positional information to synchronize two
applications.  In this case, you want the information to arrive as
quickly as possible, and if you lose a packet, you'd rather get new
updated information rather than have the system waste time resending a
packet that is becoming older and older with every retry.

\section{Usage}

All of the \texttt{SGIOChannel} derived classes have exactly the same usage
interface once an instance has been created.

\subsection{Opening the Device}

\begin{verbatim}
// If specified as a server (in direction for now) open the master
// listening socket.  If specified as a client (out direction),
// open a connection to a server.
bool open( SGProtocolDir dir );
\end{verbatim}

The \texttt{open()} method requires a direction.  Direction can be one
of:

\begin{itemize}
\item \texttt{SG\_IO\_IN} -- data will be flowing into this object to
  the application.
\item \texttt{SG\_IO\_OUT} -- data will be flowing out of this object
  from the application.
\item \texttt{SG\_IO\_BI} -- data will be flowing in both directions.
\item \texttt{SG\_IO\_NONE} -- data will not be flowing in either
  direction.  This is here for the sake of completeness. 
\end{itemize}

\subsection{Reading Data}

\begin{verbatim}
int read( char *buf, int length );
int readline( char *buf, int length );
\end{verbatim}

The \texttt{read()} method is modeled after the \texttt{read()} Unix
system call.  You must provide a pointer to a character buffer that
has enough allocated space for your potential read.  You can also
specify the maximum number of bytes allowed for this particular read.
The actual number of bytes read is returned.  The \texttt{readline()}
method is similar to \texttt{read()} except that it will stop at the
first end of line encountered in the input buffer.


\subsection{Writing Data}

\begin{verbatim}
int write( char *buf, int length );
int writestring( char *str );
\end{verbatim}

The \texttt{write()} method is modeled after the \texttt{write()} Unix
system call and is analogous to the \texttt{read()} method.  You
provide a pointer to a buffer of data, and then length of that data to
be written out.  The number of bytes written is returned.  The
\texttt{writestring()} method is a simple wrapper that will calculate
the length of a null terminated character array and write it out.


\subsection{Cleaning Up}

\begin{verbatim}
bool close();
\end{verbatim}

The \texttt{close()} method is modeled after the \texttt{close()} Unix
system call and will close an open device.  You should call this
method when you are done using your IO class, before it is destructed.


\end{document}
